.\"
.\"	$OpenBSD: SSL_CTX_set_client_CA_list.3,v 1.2 2014/12/02 14:11:01 jmc Exp $
.\"
.Dd $Mdocdate: December 2 2014 $
.Dt SSL_CTX_SET_CLIENT_CA_LIST 3
.Os
.Sh NAME
.Nm SSL_CTX_set_client_CA_list ,
.Nm SSL_set_client_CA_list ,
.Nm SSL_CTX_add_client_CA ,
.Nm  SSL_add_client_CA
.Nd set list of CAs sent to the client when requesting a client certificate
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft void
.Fn SSL_CTX_set_client_CA_list "SSL_CTX *ctx" "STACK_OF(X509_NAME) *list"
.Ft void
.Fn SSL_set_client_CA_list "SSL *s" "STACK_OF(X509_NAME) *list"
.Ft int
.Fn SSL_CTX_add_client_CA "SSL_CTX *ctx" "X509 *cacert"
.Ft int
.Fn SSL_add_client_CA "SSL *ssl" "X509 *cacert"
.Sh DESCRIPTION
.Fn SSL_CTX_set_client_CA_list
sets the
.Fa list
of CAs sent to the client when requesting a client certificate for
.Fa ctx .
.Pp
.Fn SSL_set_client_CA_list
sets the
.Fa list
of CAs sent to the client when requesting a client certificate for the chosen
.Fa ssl ,
overriding the setting valid for
.Fa ssl Ns 's
.Vt SSL_CTX
object.
.Pp
.Fn SSL_CTX_add_client_CA
adds the CA name extracted from
.Fa cacert
to the list of CAs sent to the client when requesting a client certificate for
.Fa ctx .
.Pp
.Fn SSL_add_client_CA
adds the CA name extracted from
.Fa cacert
to the list of CAs sent to the client when requesting a client certificate for
the chosen
.Fa ssl ,
overriding the setting valid for
.Fa ssl Ns 's
.Va SSL_CTX
object.
.Sh NOTES
When a TLS/SSL server requests a client certificate (see
.Fn SSL_CTX_set_verify ) ,
it sends a list of CAs for which it will accept certificates to the client.
.Pp
This list must explicitly be set using
.Fn SSL_CTX_set_client_CA_list
for
.Fa ctx
and
.Fn SSL_set_client_CA_list
for the specific
.Fa ssl .
The list specified overrides the previous setting.
The CAs listed do not become trusted
.Po
.Fa list
only contains the names, not the complete certificates
.Pc ;
use
.Xr SSL_CTX_load_verify_locations 3
to additionally load them for verification.
.Pp
If the list of acceptable CAs is compiled in a file, the
.Xr SSL_load_client_CA_file 3
function can be used to help importing the necessary data.
.Pp
.Fn SSL_CTX_add_client_CA
and
.Fn SSL_add_client_CA
can be used to add additional items the list of client CAs.
If no list was specified before using
.Fn SSL_CTX_set_client_CA_list
or
.Fn SSL_set_client_CA_list ,
a new client CA list for
.Fa ctx
or
.Fa ssl
(as appropriate) is opened.
.Pp
These functions are only useful for TLS/SSL servers.
.Sh RETURN VALUES
.Fn SSL_CTX_set_client_CA_list
and
.Fn SSL_set_client_CA_list
do not return diagnostic information.
.Pp
.Fn SSL_CTX_add_client_CA
and
.Fn SSL_add_client_CA
have the following return values:
.Bl -tag -width Ds
.It 0
A failure while manipulating the
.Dv STACK_OF Ns
.Pq Vt X509_NAME
object occurred or the
.Vt X509_NAME
could not be extracted from
.Fa cacert .
Check the error stack to find out the reason.
.It 1
The operation succeeded.
.El
.Sh EXAMPLES
Scan all certificates in
.Fa CAfile
and list them as acceptable CAs:
.Bd -literal
SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
.Ed
.Sh SEE ALSO
.Xr ssl 3 ,
.Xr SSL_CTX_load_verify_locations 3 ,
.Xr SSL_get_client_CA_list 3 ,
.Xr SSL_load_client_CA_file 3
